<?php
/**
 * Contains interface definition for URL.
 *
 * @package     mpUrlInfo
 * @author      Murat Purc <murat@purc.de>
 * @copyright   Copyright (c) 2008-2010 Murat Purc (http://www.purc.de)
 * @license     http://www.gnu.org/licenses/gpl-2.0.html - GNU General Public License, version 2
 * @version     $Id: mpUrlInterface.php 2 2010-02-17 15:47:06Z purcaholic $
 */


/**
 * Interface for URL representation.
 *
 * @package     mpUrlInfo
 * @author      Murat Purc <murat@purc.de>
 */
interface mpUrlInterface
{
    /**
     * Returns string representation of self.
     *
     * @return  string
     */
    public function __toString();

    /**
     * Checks passed url object against equality with self.
     *
     * @param   mpUrlInterface  $url  Url to check
     * @return  bool
     */
    public function equals(mpUrlInterface $url);

    /**
     * Compares passed url with self, excluding the fragment component.
     *
     * @param   mpUrlInterface  $url  Url to check
     * @return  bool
     */
    public function isSameUrl(mpUrlInterface $url);

    /**
     * Sets the argument separator for query parameter.
     *
     * @param   string  $argSeparator
     * @return  void
     */
    public static function setArgSeparator($argSeparator);

    /**
     * Returns the current set argument separator.
     *
     * @return  string
     */
    public static function getArgSeparator();

    /**
     * Sets the url object with passed url.
     *
     * @param   string  $url
     * @return  void
     */
    public function setUrl($url);

    /**
     * Sets the url scheme (e. g. http, https, etc...)
     *
     * @param   string  $scheme
     * @return  void
     * @throws  Exception  If passed scheme isn't supported
     */
    public function setScheme($scheme);

    /**
     * Returns url scheme
     *
     * @return  string
     */
    public function getScheme();

    /**
     * Sets host name.
     *
     * @param   string  $host
     * @return  void
     */
    public function setHost($host);

    /**
     * Returns host name.
     *
     * @return  string
     */
    public function getHost();

    /**
     * Sets port number of host
     *
     * @param   int  $port
     * @return  void
     * @throws  Exception  If passed port is invalid
     */
    public function setPort($port);

    /**
     * Returns port number of host
     *
     * @return  int
     */
    public function getPort();

    /**
     * Sets the user name.
     *
     * @param   string  $user
     * @return  void
     */
    public function setUser($user);

    /**
     * Returns user name.
     *
     * @return  string
     */
    public function getUser();

    /**
     * Sets the user password.
     *
     * @param   string  $pass
     * @return  void
     */
    public function setPass($pass);

    /**
     * Returns user password.
     *
     * @return  string
     */
    public function getPass();

    /**
     * Sets the path.
     *
     * @param   string  $path
     * @return  void
     */
    public function setPath($path);

    /**
     * Returns path, with filename, if filename exists.
     *
     * @return  string
     */
    public function getPath();

    /**
     * Sets filename.
     *
     * @param   string
     * @return  void
     */
    public function setFilename($filename);

    /**
     * Returns filename if exists.
     *
     * @return  string
     */
    public function getFilename();

    /**
     * Sets extension.
     *
     * @param   string
     * @return  void
     */
    public function setExtension($extension);

    /**
     * Returns extension if exists.
     *
     * @return  string
     */
    public function getExtension();

    /**
     * Sets the query.
     *
     * @param   string  $query
     * @return  void
     */
    public function setQuery($query);

    /**
     * Returns query.
     *
     * @return  string
     */
    public function getQuery();

    /**
     * Sets a query parameter and it's value.
     *
     * Examples:
     * <code>
     * // to set foo=bar
     * $url->setQueryParameter('foo', 'bar');
     *
     * // to set foo[0]=bar&foo[1]=bar2
     * $url->setQueryParameter('foo', array('bar', 'bar2'));
     * </code>
     *
     * @param   string        $parameter  Name of query parameter
     * @param   string|array  $value      Either the value or a array of values.
     * @return  void
     */
    public function setQueryParameter($parameter, $value);

    /**
     * Returns either all query parameter as a assoziative array, or the value of a specific query
     * parameter.
     *
     * @param   string|null  $parameter  Name of parameter or null to get all parameter
     * @param   string|null  $default    Default value to return, in conjunction with passed $parameter
     * @return  string|array|null  Depends of incomming parameter
     */
    public function getQueryParameter($parameter=null, $default=null);

    /**
     * Removes existing query parameter.
     *
     * @param   string  $parameter  Name of query parameter to remove
     * @return  void
     */
    public function removeQueryParameter($parameter);

    /**
     * Sets the fragment.
     *
     * @param   string  $fragment
     * @return  void
     */
    public function setFragment($fragment);

    /**
     * Returns the fragment.
     *
     * @return  string
     */
    public function getFragment();

    /**
     * Builds and returns the Url.
     *
     * @param  string
     */
    public function build();

    /**
     * Build a url using passed components array.
     *
     * @param   array   $comp  Assoziative array created by parse_url()
     * @return  string  The composed Url
     */
    public static function buildByComponents(array $comp);

    /**
     * Removes beginning and ending path delemiter from path and returns it back.
     *
     * @param   string  $path
     * @return  string
     */
    public static function trimPath($path);

}
